Skip to content

Clarify tool visibility#1562

Open
jayaraman-venkatesan wants to merge 2 commits intomodelcontextprotocol:mainfrom
jayaraman-venkatesan:feature/sep-2200-tool-result-visibility
Open

Clarify tool visibility#1562
jayaraman-venkatesan wants to merge 2 commits intomodelcontextprotocol:mainfrom
jayaraman-venkatesan:feature/sep-2200-tool-result-visibility

Conversation

@jayaraman-venkatesan
Copy link
Copy Markdown
Contributor

@jayaraman-venkatesan jayaraman-venkatesan commented May 6, 2026

feat(sep-2200): align tool result content visibility with SEP-2200

Closes #1552

Summary

Brings the C# SDK into compliance with SEP-2200 — "Clarify tool result content visibility"

SEP-2200 clarifies that CallToolResult.content is model-oriented (may be a prose summary) and CallToolResult.structuredContent is machine-oriented (strict JSON for programmatic consumers). Clients SHOULD prefer content for model context and SHOULD NOT forward both fields verbatim to the LLM. The wire format is unchanged.

What

Behavioural fix McpClientTool.InvokeCoreAsync

Removed result.StructuredContent is null from the gate. The Content-block conversion path now triggers whenever there's no protocol-level info to preserve (IsError=true or non-empty Meta), regardless of whether StructuredContent is also set.

See THIS comment for more info.

- if (result.IsError is not true &&
-     result.StructuredContent is null &&
-     result.Meta is not { Count: > 0 })                                                                                                                                                                        
+ if (result.IsError is not true &&
+     result.Meta is not { Count: > 0 })                                                                                                                                                                        

XML doc updates (no behaviour change)

  • CallToolResult.Content / StructuredContent — model-vs-machine semantics + the SEP-2200 selection rule.
  • [McpServerTool].UseStructuredContent / OutputSchemaType — call out the default JSON-dump behaviour and point to the recommended decoupled-fields pattern.
  • McpServerToolCreateOptions.UseStructuredContent / OutputSchema — same wording mirrored on the options surface.
  • McpClient.CallToolAsync<remarks> explaining which field to forward to the model and which to consume programmatically.
    ### Sample
    New samples/EverythingServer/Tools/WeatherStructuredTool.cs demonstrating the SEP-2200 recommended pattern: returns a CallToolResult with model-friendly prose in Content ("It's 72°F and sunny in Paris …") alongside machine-friendly JSON in StructuredContent ({"city":"Paris","tempF":72,…}), with the schema advertised via OutputSchemaType = typeof(WeatherReading).

Behavioural change call-out

Clients embedding this SDK in IChatClient flows will stop double-feeding content + structuredContent to the LLM.
The default [McpServerTool(UseStructuredContent=true)] JSON-dump-into-both shape is preserved (SEP-2200 explicitly permits it, though considers it suboptimal).

No wire change

SEP-2200 itself is non-wire-breaking: same content, same structuredContent, same types. Only the SDK's consumption of the wire result changed.

Test plan

  • dotnet test tests/ModelContextProtocol.Tests (net10.0): 1887 passed, 0 failed, 5 skipped.
  • Targeted: red-then-green confirmed for StructuredContentTool_PrefersContentBlocksForModel
  • dotnet build src/ModelContextProtocol.Core and dotnet build samples/EverythingServer: 0 warnings, 0 errors across all target frameworks.

…ent vs. structuredContent semantics and add decoupled-fields sample
…ot full CallToolResult) when StructuredContent is also present
@jayaraman-venkatesan jayaraman-venkatesan marked this pull request as ready for review May 6, 2026 02:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SEP-2200: Clarify tool result content visibility

1 participant